package com.jade.bss.customer.role;

import java.util.List;

import com.jade.bss.customer.CustomerException;
import com.jade.framework.base.criterion.Criteria;
import com.jade.framework.base.util.PagingList;

/**
 * 角色数据访问接口，包括角色的增删查改以及角色与Principal的管理。
 *
 * @author sky
 * @version 1.0 13-4-18 上午9:37
 */
public interface RoleDao
{
    /**
     * Adds a new role. It's neccesary to check the role's name confliction.
     *
     * @param role the role to be added.
     * @return the ID of new role.
     * @throws CustomerException if there is an existed role that has the same name as
     *                           the role to be added or some reasons that cause the operation can't be completed,
     *                           such as database error.
     */
    public int addRole(RoleEntry role)
            throws CustomerException;

    /**
     * Removes an existed role with the specified ID..
     *
     * @param role the role to be removed
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void removeRole(RoleEntry role)
            throws CustomerException;

    /**
     * Modifies the role information. It's neccesary to check if there is another role that has the same name as
     * the new name of this role.
     *
     * @param role the role with the new information
     * @throws CustomerException if there is an existed role that has the same name as
     *                           the role to be added or some reasons that cause the operation can't be completed,
     *                           such as database error.
     */
    public void updateRole(RoleEntry role)
            throws CustomerException;

    /**
     * Returns the role with the specified ID. If any role can't be found, return null.
     *
     * @param id the role's ID
     * @return the role with the specified ID.
     */
    public RoleEntry getRole(int id);

    /**
     * Returns the role with the specified name. If any role can't be found, return null.
     *
     * @param name the role's name
     * @return the role with the specified name.
     */
    public RoleEntry getRole(String name);

    /**
     * Returns the list of all roles.
     *
     * @return the list of all roles.
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public List<RoleEntry> listRole();

    /**
     * Returns the list of all roles by type.
     *
     * @return the list of all roles.
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public List<RoleEntry> listRole(String type);

    /**
     * Search the list of roles.
     *
     * @param criteria query's criteria
     * @return query's result
     */
    public PagingList<RoleEntry> queryRole(Criteria criteria);

    /**
     * Modifies the role's status.
     *
     * @param id     the role's ID.
     * @param status the new status of the role.
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void updateStatus(int id, int status)
            throws CustomerException;


//    /**
    //     * 获取角色与身份的对应关系。
    //     *
    //     * @param principalType 身份类型
    //     * @param principalName 身份名称
    //     * @param roleId        角色标识
    //     * @return PrincipalRole对象
    //     */
    //    public PrincipalRole getPrincipalRole(String principalType, String principalName, int roleId);
    //
    //    /**
    //     * List the all principal roles that belong to the specified principal.
    //     *
    //     * @param principalType principal type
    //     * @param principalName principal name
    //     * @return the list of principal role
    //     */
    //    public List<PrincipalRole> listPrincipalRole(String principalType, String principalName);
    //
    //    /**
    //     * List the all principal roles that belong to the specified role.
    //     *
    //     * @param roleId role identifier
    //     * @return the list of principal role
    //     */
    //    public List<PrincipalRole> listPrincipalRole(int roleId);
    //
    //    /**
    //     * 添加角色与身份的对应关系.
    //     *
    //     * @param pr 身份角色关系对象
    //     */
    //    public void addPrincipalRole(PrincipalRole pr);
    //
    //    /**
    //     * 清除一个身份的所有角色关系。
    //     *
    //     * @param principalType 身份类型
    //     * @param principalName 身份名称
    //     */
    //    public void removePrincipalRole(String principalType, String principalName);
    //
    //    /**
    //     * 清除一个角色的所有身份关系。
    //     *
    //     * @param roleId 角色标识
    //     */
    //    public void removePrincipalRole(int roleId);
    //
    //    /**
    //     * 清除指定的角色与身份对应关系。
    //     *
    //     * @param principalType 身份类型
    //     * @param principalName 身份名称
    //     * @param roleId        角色标识
    //     */
    //    public void removePrincipalRole(String principalType, String principalName, int roleId);
}
